ES 查询与运维命令速查

本篇把日常最常用的请求收在一起，按「集群与节点 / _cat / 索引与文档 / 查询与聚合」分表。默认服务地址是 http://localhost:9200，示例里的索引名按实际替换。

通用约定

• 方法语义：GET 查、PUT 建（幂等）、POST 写/执行、DELETE 删、HEAD 探活。
• 加 ?pretty：返回带缩进的 JSON，人看方便，脚本里别加。
• 请求体一律带 header：-H 'Content-Type: application/json'，否则 8.x 会拒绝解析。
• NDJSON 接口（_bulk、_msearch）用 Content-Type: application/x-ndjson，每行一个 JSON，末尾必须有换行。
• filter_path 裁剪返回：?filter_path=status,number_of_nodes，脚本里取值更省事。
• ?human 让大小、时间带单位（1.2gb、3.4s），?bytes=gb 指定单位。

集群与节点

方法	路径	说明
GET	/_cluster/health	集群三色、节点数、分片数
GET	/_cluster/health?level=indices	带上每个索引的健康明细
GET	/_cluster/health?wait_for_status=yellow&timeout=30s	阻塞等待集群达到指定状态
GET	/_cluster/stats	集群级统计：文档数、存储、内存
GET	/_cluster/state	集群状态元数据（很大，慎用）
GET	/_cluster/settings?include_defaults=true	当前生效的集群设置
PUT	/_cluster/settings	修改动态集群设置
GET	/_cluster/allocation/explain	解释分片为什么没分配
POST	/_cluster/reroute?retry_failed=true	重试失败的分片分配
GET	/_nodes	节点列表与基本信息
GET	/_nodes/stats	节点全量指标（JVM、OS、FS、索引）
GET	/_nodes/stats/jvm,os,fs	只取关心的几类指标
GET	/_nodes/hot_threads	当前最忙的线程栈，卡顿排查首选
GET	/_tasks	正在跑的任务，找失控查询
POST	/_tasks/节点ID:任务ID/_cancel	取消指定任务
GET	/_snapshot/仓库名/_all	快照列表与状态
POST	/_snapshot/仓库名/snap名/_restore	从快照恢复
GET	/_slm/policy	快照生命周期策略
GET	/{index}/_ilm/explain	索引的 ILM 执行状态

建仓库、建快照、恢复

PUT /_snapshot/fs_backup
{
  "type": "fs",
  "settings": {
    "location": "/data/es/backup",
    "compress": true
  }
}

PUT /_snapshot/fs_backup/snap-20251025?wait_for_completion=false
{
  "indices": "logs-*,articles",
  "ignore_unavailable": true,
  "include_global_state": false
}

POST /_snapshot/fs_backup/snap-20251025/_restore
{
  "indices": "articles",
  "rename_pattern": "(.+)",
  "rename_replacement": "restored_$1"
}

分片分配

GET /_cluster/allocation/explain
{
  "index": "logs-2025.10.25",
  "shard": 0,
  "primary": false
}

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_replica": {
        "index": "logs-2025.10.25",
        "shard": 0,
        "node": "es-node-2"
      }
    }
  ]
}

_cat 命令

_cat 系列是纯文本表格，?v 带表头，?h= 选列，?s= 排序，?format=json 输出 JSON。完整清单用 GET /_cat 或 GET /_cat/help。

命令	说明
_cat/health?v	集群健康概览
_cat/master?v	当前 master 节点
_cat/nodes?v	节点角色、堆、CPU、负载、磁盘
_cat/nodeattrs?v	节点自定义属性（机架、区域）
_cat/indices?v&s=store.size:desc	索引列表，按大小排序
_cat/shards?v	分片分布与状态
_cat/allocation?v	每节点分片数、磁盘占用、剩余
_cat/segments?v	段数量与大小
_cat/recovery?v&active_only=true	正在恢复的分片与进度
_cat/thread_pool?v	线程池活跃、队列、拒绝数
_cat/pending_tasks?v	积压的集群任务
_cat/fielddata?v&bytes=gb	fielddata 内存占用
_cat/aliases?v	别名与索引的对应关系
_cat/templates?v	索引模板列表
_cat/count?v	文档总数
_cat/plugins?v	已安装插件
_cat/health?v&h=status,node.total,shards	只取几列
_cat/nodes?v&h=name,heap.percent,disk.avail,cpu,load_1m	巡检常用列组合

索引与文档

索引

方法	路径	说明
PUT	/{index}	建索引（可带 settings 和 mappings）
GET	/{index}	查看索引定义
DELETE	/{index}	删除索引（数据不可恢复）
GET	/{index}/_mapping	查看 Mapping
PUT	/{index}/_mapping	新增字段（已有字段类型不能改）
GET	/{index}/_settings	查看索引设置
PUT	/{index}/_settings	修改副本数、refresh_interval 等
POST	/{index}/_close	关闭索引（不可读写，省资源）
POST	/{index}/_open	打开索引
POST	/{index}/_refresh	立即刷新，让写入可搜索
POST	/{index}/_flush	刷盘并清空 translog
POST	/{index}/_forcemerge?max_num_segments=1	合并段（只对只读索引做）
POST	/{index}/_cache/clear?fielddata=true	清 fielddata 缓存
POST	/_reindex	重建索引搬数据
POST	/_aliases	批量增删别名
GET	/_index_template	索引模板列表
PUT	/_index_template/{name}	创建/更新索引模板

PUT /articles/_settings
{
  "index": {
    "number_of_replicas": 1,
    "refresh_interval": "5s"
  }
}

PUT /articles/_mapping
{
  "properties": {
    "summary": { "type": "text" },
    "updated_at": { "type": "date" }
  }
}

文档

方法	路径	说明
PUT	/{index}/_doc/{id}	指定 ID 写入（覆盖，幂等）
POST	/{index}/_doc	自动生成 ID 写入
POST	/{index}/_create/{id}	仅当文档不存在时创建
GET	/{index}/_doc/{id}	按 ID 实时读取
HEAD	/{index}/_doc/{id}	判断文档是否存在
POST	/{index}/_update/{id}	局部更新字段
DELETE	/{index}/_doc/{id}	删除文档
POST	/_bulk	批量写（NDJSON）
GET	/_mget	批量按 ID 读
GET	/{index}/_count	统计文档数
POST	/{index}/_delete_by_query	按条件批量删除（重操作）
POST	/{index}/_update_by_query	按条件批量更新（重操作）

POST /articles/_update/1
{
  "doc": {
    "status": "archived"
  }
}

POST /_mget
{
  "docs": [
    { "_index": "articles", "_id": "1" },
    { "_index": "articles", "_id": "2" }
  ]
}

bulk 请求格式

{"index":{"_index":"articles","_id":"10"}}
{"title":"运维手册","status":"published"}
{"update":{"_index":"articles","_id":"10"}}
{"doc":{"status":"archived"}}
{"delete":{"_index":"articles","_id":"11"}}

curl -X POST "http://localhost:9200/_bulk" \
  -H 'Content-Type: application/x-ndjson' \
  --data-binary @actions.ndjson

查询与聚合

常用查询

场景	写法	说明
全文检索	match	对 text 字段分词后匹配
短语匹配	match_phrase	词序相邻
多字段检索	multi_match	可用 ^ 加权
精确匹配	term / terms	keyword 字段
范围	range	gte / gt / lte / lt
组合	bool	must / filter / should / must_not
存在性	exists	字段是否存在且有值
前缀	prefix	keyword 字段前缀匹配
通配	wildcard	性能差，慎用
模糊	fuzzy	拼写容错
地理	geo_distance	按距离圈选

GET /articles/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "Elasticsearch" } }
      ],
      "filter": [
        { "term": { "status": "published" } },
        { "range": { "created_at": { "gte": "now-30d/d" } } }
      ],
      "must_not": [
        { "term": { "tags": "deprecated" } }
      ]
    }
  },
  "from": 0,
  "size": 20,
  "sort": [
    { "created_at": "desc" },
    { "_id": "asc" }
  ],
  "_source": ["title", "created_at"],
  "track_total_hits": true
}

深分页用 search_after：

GET /articles/_search
{
  "size": 20,
  "sort": [
    { "created_at": "desc" },
    { "_id": "asc" }
  ],
  "search_after": ["2025-10-01T08:00:00", "abc123"]
}

聚合

GET /articles/_search
{
  "size": 0,
  "aggs": {
    "by_status": {
      "terms": { "field": "status", "size": 10 },
      "aggs": {
        "avg_views": { "avg": { "field": "view_count" } }
      }
    },
    "per_month": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month",
        "format": "yyyy-MM"
      }
    }
  }
}

聚合类型	用途
terms	按字段值分组，类似 group by
date_histogram	按时间分桶
histogram	按数值区间分桶
avg / sum / min / max	数值统计
cardinality	去重计数（近似）
percentiles	分位数（P95、P99）
nested	针对 nested 字段聚合
composite	分页聚合，桶很多时用

一次多个查询

{"index":"articles"}
{"query":{"match":{"title":"elasticsearch"}},"size":3}
{"index":"articles"}
{"query":{"term":{"status":"published"}},"size":3}

curl -X POST "http://localhost:9200/_msearch" \
  -H 'Content-Type: application/x-ndjson' \
  --data-binary @queries.ndjson

状态码与常见错误

状态码	错误	含义与处理
200	正常	查询成功，注意 timed_out 字段
201	已创建	索引/文档创建成功
400	mapper_parsing_exception	字段类型与 Mapping 不符，改数据或 Mapping
400	illegal_argument_exception	参数写错，比如聚合字段是 text
404	index_not_found_exception	索引不存在，检查名字或先创建
404	document_missing_exception	文档不存在
409	version_conflict_engine_exception	并发写冲突，重试或加 ?version=
429	es_rejected_execution_exception	线程池队列满，退避重试 + 降并发
503	unavailable_shards_exception	主分片未分配，先看集群是否 red

# 一个带完整错误信息的查询示例
curl -s -X GET "http://localhost:9200/articles/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '
{
  "query": { "term": { "title": "运维" } },
  "size": 1
}
'

term 查 text 字段不会报错，只会「查不到」——这类静默失败最费时间，排查时先用 _mapping 确认字段类型。